Scoreboard insertion guide

This guide will help you seamlessly integrate professional scoreboard functionality into your sports broadcasts. Whether you're streaming basketball games, football matches, or any other competitive events, you'll learn everything you need to create, update, and manage scoreboards to enhance your viewers' experience.

Prerequisites

Before we dive in, make sure you have the following ready:

Valid API key (for authentication)
Python 3.x environment (latest stable version recommended)
requests library (for making HTTP requests)

API Reference

1. Create Scoreboard

Endpoint: POST /live/v1/live-streams
Purpose: Set up initial scoreboard configuration when creating a new stream
Use Case: When starting a new game broadcast, use this endpoint to configure your scoreboard's style and position, ensuring viewers see the score from the very beginning

2. Update Scoreboard Content

Endpoint: PUT /live/v1/live-streams/{stream-id}/generated-watermark
Purpose: Update the content displayed on the scoreboard in real-time
Use Case: Keep your viewers informed by instantly updating the score as the game progresses

3. Update Scoreboard Settings

Endpoint: PUT /live/v1/live-streams/{stream-id}/generated-watermark-settings
Purpose: Fine-tune the scoreboard's visual properties
Use Case: Adjust the position, size, or opacity of your scoreboard to perfectly match your broadcast's look and feel
Note: This setting can only be configured when the stream is in idle state and will take effect in the next broadcast

4. Delete Scoreboard

Endpoint: DELETE /live/v1/live-streams/{stream-id}/generated-watermark
Purpose: Remove the scoreboard from your stream
Use Case: Clean up after the game ends or temporarily hide the scoreboard when needed

Note：More detailed information about the API can be viewed here：API-Scoreboard

Implementation Guide

1. Initialize Scoreboard

When setting up your broadcast, you'll need to configure the scoreboard through the generate_watermark parameter. Here are the key settings and our recommendations:

Load timeout: Set to 5-10 seconds for reliable loading
Scoreboard size: Aim for 50%-80% width for the perfect balance of visibility and aesthetics
Display position: Place at the top or bottom of the screen to avoid obscuring the action
Opacity: Use 80%-100% to ensure your scoreboard blends seamlessly with the broadcast

2. Scoreboard Property Configuration

Here's a comprehensive guide to all customizable properties you can adjust to perfect your scoreboard:

Property	Description	Example Value	Best Practice
width	Width percentage	"50%"	Use 50%-80% for optimal visibility without overwhelming the screen
height	Height percentage	"50%"	Adjust based on content to avoid crowding or wasted space
vertical_margin	Vertical margin	"0px"	Start at 0px and fine-tune until perfectly positioned
vertical_align	Vertical alignment	"bottom"	Top or bottom alignment typically works best for clean layout
horizontal_margin	Horizontal margin	"0px"	Use in combination with alignment for precise positioning
horizontal_align	Horizontal alignment	"left"	Left alignment is most natural for viewers
opacity	Opacity level	"100%"	Adjust between 80%-100% to match your broadcast's lighting

Code Examples

Create Stream with Scoreboard

Here's how to create a new stream with a professional scoreboard setup - feel free to use this code as-is or customize it to your needs:

import requests
import json

url = "https://api.visionular.com/live/v1/live-streams"

payload = {
    "user_metadata": "demo",
    "policy": ["public"],
    "reconnect_window": 0,
    "latency_mode": "standard",
    "generate_watermark": {
        "overlay_settings": {
            "width": "50%",
            "height": "50%",
            "vertical_margin": "0px",
            "vertical_align": "bottom",
            "horizontal_margin": "0px",
            "horizontal_align": "left",
            "opacity": "100%"
        },
        "page_load_timeout": 5
    },
    "max_continuous_duration": 43200,
    "record": False
}

headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Basic YOUR_API_KEY'
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Update Scoreboard Content

When the score changes, use this code to quickly update your display. In this example, we are using https://www.scorebird.com to deliver the HTML for insertion into the live stream.

import requests
import json

url = "https://api.visionular.com/live/v1/live-streams/{stream-id}/generated-watermark"

payload = {
    "generate_watermark": {
        "url": "https://widget.scorebird.com/broadcast-overlay.html?parameters"
    }
}

headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Basic YOUR_API_KEY'
}

response = requests.put(url, headers=headers, json=payload)
print(response.json())

Fine-tune Scoreboard Settings

Need to adjust your scoreboard's position or size? Here's how:

Note: This setting can only be configured when a stream is inactive and will take effect at the start of your next live broadcast. To make changes, you must first stop your current stream, update the settings, and then restart your live broadcast.

import requests
import json

url = "https://api.visionular.com/live/v1/live-streams/{stream-id}/generated-watermark-settings"

payload = {
    "generate_watermark": {
        "overlay_settings": {
            "width": "80%",
            "height": "80%",
            "vertical_margin": "20px",
            "vertical_align": "top",
            "horizontal_margin": "20px",
            "horizontal_align": "left",
            "opacity": "100%"
        },
        "page_load_timeout": 5
    }
}

headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Basic YOUR_API_KEY'
}

response = requests.put(url, headers=headers, json=payload)
print(response.json())

Visionular